Structure buf

Structure buf_t

The buf_t structure describes a block data transfer. It is designed to represent the transfer (in or out) of a sequence of adjacent, fixed-size blocks from a random-access device to a block of contiguous memory. The size of one device block is NBPSCTR, declared in sys/param.h. For a detailed discussion of the buf_t, see the buf(D4) reference page.

The buf_t is used internally in IRIX by the paging I/O system to manage queues of physical pages, and by filesystems to manage queues of pages of file data. The paging system and filesystems are the primary clients of the pfxstrategy() entry point to a block device driver, so it is only natural that a buf_t pointer is the input argument to pfxstrategy().

Tip: The idbg kernel debugging tool has several functions related to displaying the contents of buf_t objects. See "Commands to Display buf_t Objects".

Fields of buf_t

The fields of the buf_t are declared in sys/buf.h, which is included by sys/ddi.h. This header file also declares the names of many kernel functions that operate on buf_t objects. (Many of those functions are not supported as part of the DDABI. You should only use kernel functions that have reference pages.)

Because buf_t is used by so many software components, it has many fields that are not relevant to device driver needs, as well as some fields that have multiple uses. The relevant fields include the following:

b_edev dev_t giving device major and minor numbers.
b_flags Operational flags; for a detailed list see buf(D4).
b_forw, b_back, av_forw, av_back Queuing pointers, available for driver use within the pfxstrategy() routine.
b_un.b_addr Sometimes the kernel virtual address of the buffer, depending on the b_flags setting BP_ISMAPPED.
b_bcount Number of bytes to transfer.
b_blkno Starting logical block number on device.
b_iodone Address of a driver internal function to be called on I/O completion.
b_resid Number of bytes not transferred, set at completion to 0 unless an error occurs.
b_error Error code, set at completion of I/O.

Using the Logical Block Number

The logical block number is the number of the 512-byte block in the device. The "device" is encoded by the minor device number that you can extract from b_edev. It might be a complete device surface, or it might be a partition within a larger device (for example, the IRIX disk device drivers support different minor device numbers for different disk partitions).

The pfxstrategy() routine may have to translate the logical block number based on the driver's information about device partitioning and device geometry (sector size, sectors per track, tracks per cylinder).

Buffer Location and b_flags

The data buffer represented by a buf_t can be in one of two places, depending on bits in b_flags.

When the macro BP_ISMAPPED(buf_t-address) returns true, the buffer is in kernel virtual memory and its virtual address is in b_un.b_addr.

When BP_ISMAPPED(buf_t-address) returns false, the buffer is described by a chain of pfdat structures (declared in sys/pfdat.h, but containing no fields of any use to a device driver). In this case, b_un.b_addr contains only an offset into the first page frame of the chain. See "Managing Buffer Virtual Addresses" for a method of mapping an unmapped buffer.

b_edev	dev_t giving device major and minor numbers.
b_flags	Operational flags; for a detailed list see buf(D4).
b_forw, b_back, av_forw, av_back	Queuing pointers, available for driver use within the pfxstrategy() routine.
b_un.b_addr	Sometimes the kernel virtual address of the buffer, depending on the b_flags setting BP_ISMAPPED.
b_bcount	Number of bytes to transfer.
b_blkno	Starting logical block number on device.
b_iodone	Address of a driver internal function to be called on I/O completion.
b_resid	Number of bytes not transferred, set at completion to 0 unless an error occurs.
b_error	Error code, set at completion of I/O.